BasilYes Git node
Mirrored from https://github.com/lelloman/rns-rs.git synced 19d ago
>rns-rs
A Rust implementation of Reticulum, the cryptography-based networking stack for building resilient networks with readily available hardware.
This is a faithful port of the Python reference implementation, validated with Python-generated conformance vectors and live Python/Rust interoperability tests. T383838rns-crypto and T383838rns-core are T383838no_std-compatible, making them suitable for embedded/microcontroller targets. rns-rs also extends Reticulum with features not present in the Python implementation, such as Direct Link (NAT hole punching).
Workspace Crates
┌─────────────────────────────────────────────────────────────────┬────────┬───────────────────────┐
│ Crate │ `BT383838`Fdddno_std`f`b │ Description │
├─────────────────────────────────────────────────────────────────┼────────┼───────────────────────┤
│ rns-crypto │ Yes │ Cryptographic primit… │
│ rns-core │ Yes │ Wire protocol, desti… │
│ rns-net │ No │ Network node and dri… │
│ rns-server │ No │ Batteries-included n… │
│ rns-cli │ No │ CLI programs: T383838rnsd, T383838… │
│ rns-git │ No │ Git over Reticulum: … │
│ rns-ctl │ No │ Unified daemon and c… │
│ rns-hooks │ No │ Programmable transpo… │
│ rns-hooks-abi │ Yes │ Shared ABI types and… │
│ rns-hooks-sdk │ Yes │ Guest-side T383838no_std SD… │
│ rns-stats-hook │ Yes │ Statistics hook used… │
│ rns-sentinel-hook │ Yes │ Sentinel policy hook… │
└─────────────────────────────────────────────────────────────────┴────────┴───────────────────────┘
Building
T282828
cargo build
Selected Workspace Feature Flags
The flags below are common selections accepted by root workspace build commands. This is not an exhaustive list: individual package manifests define additional crate-specific features, including the complete set of T383838rns-net T383838iface-* flags and the low-level T383838rns-hooks backend features.
┌───────────────────┬──────────────────────────────────────────────────────────────────────┐
│ Flag │ Effect │
├───────────────────┼──────────────────────────────────────────────────────────────────────┤
│ T383838rns-hooks │ Compatibility alias for T383838rns-hooks-native │
│ T383838rns-hooks-wasm │ Enables WASM hooks (compiles in wasmtime) │
│ T383838rns-hooks-native │ Enables trusted native dynamic-library hooks without wasmtime │
│ T383838rns-hooks-builtin │ Enables static built-in hooks without wasmtime or dynamic libraries │
│ T383838tls │ Enables TLS support in rns-ctl (compiles in rustls) │
│ T383838iface-ax25-kiss │ Enables T383838AX25KISSInterface (enabled by default in T383838rns-net) │
│ T383838iface-weave │ Enables Linux T383838WeaveInterface support (enabled by default in T383838rns-net) │
└───────────────────┴──────────────────────────────────────────────────────────────────────┘
T282828
cargo build --features rns-hooks # Enable native dynamic-library hooks
cargo build --features rns-hooks-native # Enable native dynamic-library hooks explicitly
cargo build --features rns-hooks-wasm # Enable WASM hooks
cargo build --features rns-hooks-builtin # Enable static built-in hooks
cargo build --features tls # Enable TLS in rns-ctl
To compile WASM guest hooks, including the examples under T383838rns-hooks/examples/, add the WASM target. The host-side Wasmtime backend itself does not require this target:
T282828
rustup target add wasm32-unknown-unknown
Running Tests
Committed conformance vectors are generated from the historical, pinned Reticulum 1.4.0 baseline. The current upstream reference is Reticulum 1.4.2, which is exercised separately by the live Python/Rust interop CI lane; see UPSTREAM.md for the exact commits and acceptance scope.
T282828
# Generate fixtures from the pinned Reticulum 1.4.0 checkout
RETICULUM_UPSTREAM_DIR=/path/to/Reticulum python3 tests/generate_vectors.py
# Run tests for the default workspace members
cargo test
# Run tests for a specific crate
cargo test -p rns-crypto
cargo test -p rns-core
cargo test -p rns-net
cargo test -p rns-cli
cargo test -p rns-git
cargo test -p rns-ctl
cargo test -p rns-hooks
Developer Checks
Standard host-side validation commands:
T282828
# Full workspace tests
cargo test --workspace
# Host-safe workspace lint
bash scripts/lint-host.sh
The lint script enables native T383838rns-hooks coverage, but intentionally does not use
workspace-wide T383838--all-features. That would enable T383838rns-crypto/espidf, which
pulls in T383838esp-idf-sys and fails on normal T383838x86_64-unknown-linux-gnu host
machines. ESP32 validation remains separate under T383838rns-esp32/.
Docker E2E Tests
There are 20 numbered Docker-based end-to-end suites that validate multi-node behaviour across chain, mesh, and star topologies. The full runner also includes standalone shared-client reconnection and T383838rns-server supervision scenarios:
T282828
# Run all Docker e2e tests
cd tests/docker && ./run-all.sh
# Run a specific suite on the default 3-node chain
cd tests/docker && ./run.sh --topology chain-3 --suite 01
rns-server
T383838rns-server is the default program to run for a single node. In the normal deployment model, it is the only binary you need to build or ship. Hook-enabled builds self-spawn T383838rnsd, T383838rns-sentineld, and T383838rns-statsd from the same executable.
If you just want to run a node, start here.
If you want to tinker with the transport internals, build custom workflows, or run pieces independently, the lower-level binaries and hook system are still available separately.
Development startup:
T282828
cargo run --bin rns-server -- start --config /path/to/node
Release-style startup:
T282828
cargo build --release --bin rns-server
./target/release/rns-server start --config /path/to/node
If you want native dynamic-library hooks enabled in the node runtime:
T282828
cargo build --release --bin rns-server --features rns-hooks
./target/release/rns-server start --config /path/to/node
Useful docs:
Interface Ingress Control
rns-rs accepts the Python-compatible ingress-control keys in any interface
section:
T282828
ingress_control = Yes
ic_max_held_announces = 256
ic_burst_hold = 60
ic_burst_freq_new = 3.5
ic_burst_freq = 12
ic_pr_burst_freq_new = 3.5
ic_pr_burst_freq = 12
egress_control = No
ec_pr_freq = 5
ic_new_time = 7200
ic_burst_penalty = 300
ic_held_release_interval = 30
Ingress control defaults to enabled on Auto, Backbone, TCP client/server, UDP,
and I2P interfaces. It defaults to disabled on local/serial/KISS/RNode/Pipe-style
interfaces. Spawned dynamic interfaces inherit the full ingress-control config
from their parent interface.
Low-Level Tools
These are lower-level building blocks for development, debugging, custom setups,
and transport tinkering. Most users should prefer T383838rns-server.
Build and run the CLI binaries:
T282828
# Run the daemon directly
cargo run --bin rnsd -- /path/to/config
# Check network status
cargo run --bin rnstatus
# Query paths
cargo run --bin rnpath
# Probe connectivity
cargo run --bin rnprobe
# Identity management
cargo run --bin rnid
# Remote shell over Reticulum
cargo run --bin rnsh -- -l -n -- /bin/sh
cargo run --bin rnsh -- <destination_hash>
Utility docs:
Git over RNS
T383838rns-git provides a repository server and Git remote helper for Reticulum links:
T282828
# Print repository and client identities
cargo run -p rns-git --bin rngit -- --print-identity
# Start the repository server after editing ~/.config/rngit/server_config
cargo run -p rns-git --bin rngit
# Configure a repository remote once git-remote-rns is on PATH
git remote add origin rns://<destination_hash>/<repository>
rns-ctl
T383838rns-ctl is a unified CLI tool that combines daemon, control server, and all CLI utilities into a single binary:
T282828
# Start the HTTP/WebSocket control server
cargo run --bin rns-ctl -- http -c /path/to/config
# Start the RNS daemon
cargo run --bin rns-ctl -- daemon -c /path/to/config
# Check network status
cargo run --bin rns-ctl -- status
# Probe path reachability
cargo run --bin rns-ctl -- probe <destination_hash>
# Display/manage path table
cargo run --bin rns-ctl -- path -t
# Identity management
cargo run --bin rns-ctl -- id -g /path/to/identity
# Manage hooks through an authenticated control server
cargo run --bin rns-ctl -- hook list --token "replace-with-token-printed-by-rns-ctl-http"
The T383838http subcommand starts an HTTP/WebSocket control server:
T282828
# Run with auth token
cargo run --bin rns-ctl -- http --token my-secret-token
# Run with disabled auth (for testing)
cargo run --bin rns-ctl -- http --disable-auth
# Run on a custom port
cargo run --bin rns-ctl -- http --port 9090
The server exposes:
• HTTP API on T383838http://localhost:8080 (configurable via T383838--port or T383838RNSCTL_HTTP_PORT)
• WebSocket endpoint at T383838ws://localhost:8080/ws
Direct Link (NAT Hole Punching)
│ rns-rs extension — this feature is not present in the original Python Reticulum implementation.
rns-rs can upgrade an existing Reticulum link to a direct peer-to-peer UDP connection, bypassing transport nodes entirely. This reduces latency and offloads bandwidth from shared infrastructure.
The protocol uses a STUN-like probe to discover public endpoints, negotiates the upgrade over the existing link's channel, then both peers simultaneously punch through their NATs.
Configuration:
• Facilitator (transport node): T383838probe_port = 4343 in T383838[reticulum]
• Client (behind NAT): T383838probe_addr = <facilitator_ip>:4343 in T383838[reticulum]
API (via rns-ctl):
• T383838POST /api/direct_connect {"link_id": "..."} — initiate upgrade
• T383838GET /api/link_events — monitor for T383838direct_established / T383838direct_failed
See docs/direct-link-protocol.md for the full protocol specification.
Hooks
│ rns-rs extension — this feature is not present in the original Python Reticulum implementation.
rns-rs includes an eBPF-inspired programmable hook system that lets users attach WASM modules or trusted native dynamic libraries to points in the transport pipeline. Hooks can inspect, filter, modify, or mirror packets, announces, links, and interfaces — without modifying rns-rs itself.
Design principles:
• Crash-safe WASM hooks — WASM traps, invalid results, and fuel exhaustion are isolated by the runtime and fail open, so processing continues as if the hook returned T383838Continue
• Trusted native hooks — native hooks run in-process and are not crash-safe; they can block, corrupt, or terminate the node and must only load trusted code
• Fuel-limited WASM — WASM invocations run with a bounded fuel budget to prevent runaway execution
• Instance persistence — WASM linear memory survives across calls, so hooks can maintain counters, caches, or bloom filters
• Native backend — native hooks are loaded with T383838dlopen/T383838LoadLibrary and run in-process for targets where Wasmtime is unavailable, such as ARMv7
• Hot-reload — hooks can be reloaded at runtime without restarting the node (T383838rns-ctl hook reload)
• Zero overhead when disabled — hook backends are behind cargo feature flags; T383838rns-hooks-native does not compile in Wasmtime
Hook points (21 total):
┌─────────────────────────┬────────────────────────────────────────────────────────────────────────┐
│ Category │ Hook Points │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────┤
│ Packet lifecycle │ T383838PreIngress, T383838PreDispatch │
│ Announce processing │ T383838AnnounceReceived, T383838PathUpdated, T383838AnnounceRetransmit │
│ Link lifecycle │ T383838LinkRequestReceived, T383838LinkEstablished, T383838LinkClosed │
│ Interface lifecycle │ T383838InterfaceUp, T383838InterfaceDown, T383838InterfaceConfigChanged │
│ Backbone peer lifecycle │ T383838BackbonePeerConnected, T383838BackbonePeerDisconnected, T383838BackbonePeerIdleTime… │
│ Per-action │ T383838SendOnInterface, T383838BroadcastOnAllInterfaces, T383838DeliverLocal, T383838TunnelSynthe… │
│ Periodic │ T383838Tick │
└─────────────────────────┴────────────────────────────────────────────────────────────────────────┘
Verdicts: each hook returns a verdict that controls what happens next:
• T383838Continue — pass through normally
• T383838Drop — block the packet/action
• T383838Modify — replace with modified data
• T383838Halt — stop the hook chain (no further hooks at this attach point are executed)
Configuration:
T282828
[hooks]
[[drop_tick]]
path = /tmp/drop_tick.so
type = native
attach_point = Tick
priority = 10
enabled = Yes
[[log_announce]]
path = /tmp/log_announce.wasm
type = wasm
attach_point = AnnounceReceived
priority = 5
enabled = Yes
CLI management:
The hook CLI talks to the HTTP control server, which enables bearer authentication by default. Pass the token printed when T383838rns-ctl http starts (or omit T383838--token only when the server was explicitly started with T383838--disable-auth):
T282828
RNSCTL_TOKEN="replace-with-token-printed-by-rns-ctl-http"
rns-ctl hook list --token "$RNSCTL_TOKEN" # list loaded hooks and their status
rns-ctl hook load <path-or-builtin-id> --point <HookPoint> --token "$RNSCTL_TOKEN" [--type wasm|native|builtin] [--priority N] [--name name]
rns-ctl hook unload <name> --point <HookPoint> --token "$RNSCTL_TOKEN" # unload a running hook
rns-ctl hook reload <name> --point <HookPoint> --path <hook_file_or_builtin_id> --token "$RNSCTL_TOKEN" [--type wasm|native|builtin]
Writing hooks:
Native hooks use the ABI types from T383838rns-hooks-abi::native and export T383838rns_hook_abi_version plus T383838rns_hook_on_call; see T383838rns-hooks/examples/native_noop and docs/native-hooks.md. Use the T383838rns-hooks-sdk crate to write WASM hooks in T383838no_std Rust. Each WASM hook exports an T383838on_hook function that receives a context and returns a verdict. Built-in hooks are linked Rust functions registered by ID; see docs/builtin-hooks.md.
┌─────────────────┬──────────────────────────────────────────────────────────────────────────────┐
│ Example │ Description │
├─────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ T383838packet_logger │ Log packets passing through a hook point │
│ T383838announce_filter │ Drop announces exceeding a configurable hop count │
│ T383838announce_dedup │ Deduplicate repeated announces using persistent state │
│ T383838allowlist │ Allow only packets from known source hashes │
│ T383838link_guard │ Guard link establishment with custom policies │
│ T383838rate_limiter │ Rate-limit packets per interface │
│ T383838metrics │ Collect counters and statistics across hook invocations │
│ T383838packet_mirror │ Mirror packets to an additional destination │
│ T383838path_modifier │ Demonstrate the Modify verdict by prepending a marker byte to packet data │
│ T383838stats_scraper │ Emit packet and announce statistics for collection by the statistics sidecar │
└─────────────────┴──────────────────────────────────────────────────────────────────────────────┘
Interoperability
rns-rs is designed to be fully interoperable with the Python Reticulum implementation. A Rust node can join an existing Reticulum network alongside Python nodes, exchange announces, establish links, and transfer resources.
The current wire-level protocol is described in docs/protocol-spec.md.
License
Served by rngit 1.4.2 - Generated in 0.14s